\defmodule {AbstractChrono}

\texttt{AbstractChrono} is a class that acts as an interface to
the system clock and calculates the CPU or system time consumed by
parts of a program.

Every object of class \texttt{AbstractChrono} acts as an independent {\em stopwatch}.
Several \texttt{AbstractChrono} objects can run at any given time.
The method \method{init}{} resets the stopwatch to zero,
\method{getSeconds}{}, \method{getMinutes}{} and \method{getHours}{}
 return its current reading,
and \method{format}{} converts this reading to a \class{String}.
The returned value includes the execution time of the method
from \texttt{AbstractChrono}.

Below is an example of how it may be used.
A stopwatch named \texttt{timer} is constructed (and initialized).
When 2.1 seconds of CPU time have been consumed,
the stopwatch is read and reset to zero.
Then, after an additional 330 seconds (or 5.5 minutes) of CPU time,
the stopwatch is read again and the value is printed to the output
in minutes.
\begin{vcode}

AbstractChrono timer = new Chrono();
\end{vcode}
\begin{latexonly}
\begin{vcode}
    \vdots \end{vcode}
\vskip -15pt \hskip 0.8in ({\em suppose 2.1 CPU seconds are used here}.)
\end{latexonly}
\begin{htmlonly}
\begin{vcode}


   suppose 2.1 CPU seconds are used here

\end{vcode}
\end{htmlonly}
\begin{vcode}
double t = timer.getSeconds();               // Here, t = 2.1
timer.init();
t = timer.getSeconds();                      // Here, t = 0.0
\end{vcode}
\begin{latexonly}
\begin{vcode}    \vdots \end{vcode}
\vskip -15pt \hskip 0.8in ({\em suppose 330 CPU seconds are used here}.)
\end{latexonly}
\begin{htmlonly}
\begin{vcode}


   suppose 330 CPU seconds are used here.

\end{vcode}
\end{htmlonly}
\begin{vcode}
t = timer.getMinutes();                      // Here, t = 5.5
System.out.println (timer.format());         // Prints: 0:5:30.00
\end{vcode}


\begin{latexonly}
\begin{hide}  %%%%%%
\paragraph{Warning:}
  Even though the ANSI/ISO macro \texttt{CLOCKS\_PER\_SEC = 1000000}
  is the number of clock ticks per second for the value
  returned by the \texttt{clock} function (so this function returns the
  number of microseconds), on some systems the value returned by \texttt{clock}
  wraps around to 0 after about 36 minutes when the type \texttt{long}
  used to measure time has only 32 bits (on some systems, the clock may
  wrap around to 0 after about 72 minutes if time is
  measured using the 32-bit type \texttt{unsigned long}).
  When the macro \texttt{USE\_ANSI\_CLOCK} in module \texttt{gdef} is undefined,
  a non-ANSI clock is used. It calls the POSIX function
  \texttt{times} to get the CPU time used by a program and the
  non-ANSI macro \texttt{CLK\_TCK} is used to get the real number of
  clock ticks per second for the system.
\end{hide}   %%%%%

\end{latexonly}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bigskip\hrule\bigskip
\begin{code}
\begin{hide}
/*
 * Class:        AbstractChrono
 * Description:  calculates CPU time of parts of a program
 * Environment:  Java
 * Software:     SSJ 
 * Copyright (C) 2001  Pierre L'Ecuyer and Universite de Montreal
 * Organization: DIRO, Universite de Montreal
 * @author       
 * @since

 * SSJ is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License (GPL) as published by the
 * Free Software Foundation, either version 3 of the License, or
 * any later version.

 * SSJ is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * A copy of the GNU General Public License is available at
   <a href="http://www.gnu.org/licenses">GPL licence site</a>.
 */
\end{hide}
package umontreal.iro.lecuyer.util;


public abstract class AbstractChrono\begin{hide} {

   private long m_second;
   private long m_microsec;
   private long[] now = new long[2];
   // tab[0] = seconds, tab[1] = microseconds

   protected abstract void getTime (long[] tab);
\end{hide}
\end{code}

%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection*{Timing functions}

\begin{code}
   public AbstractChrono()\begin{hide} {
   }\end{hide}


   public void init() \begin{hide} {
      getTime (now);
      m_second = now[0];
      m_microsec = now[1];
   }\end{hide}
\end{code}
  \begin{tabb}  Initializes this \texttt{AbstractChrono} to zero.
  \end{tabb}
\begin{code}

   public double getSeconds()\begin{hide} {
      getTime (now);
      double time = (now[1] - m_microsec)/1000000.0
             + (now[0] - m_second);
      return time;
   }\end{hide}
\end{code}
 \begin{tabb}
  Returns the CPU time in seconds used by the program since the last call to
  \method{init}{} for this \texttt{AbstractChrono}.
 \end{tabb}
\begin{htmlonly}
   \return{the number of seconds}
\end{htmlonly}
\begin{code}

   public double getMinutes()\begin{hide} {
      getTime (now);
      double time = (now[1] - m_microsec)/1000000.0
             + (now[0] - m_second);
      return time*1.666666667*0.01;
   }\end{hide}
\end{code}
 \begin{tabb}
  Returns the CPU time in minutes used by the program since the last call to
  \method{init}{} for this \texttt{AbstractChrono}.
 \end{tabb}
\begin{htmlonly}
   \return{the number of minutes}
\end{htmlonly}
\begin{code}

   public double getHours()\begin{hide} {
      getTime (now);
      double time = (now[1] - m_microsec)/1000000.0
             + (now[0] - m_second);
      return time*2.777777778*0.0001;
   }\end{hide}
\end{code}
 \begin{tabb}
  Returns the CPU time in hours used by the program since the last call to
  \method{init}{} for this \texttt{AbstractChrono}.
 \end{tabb}
\begin{htmlonly}
   \return{the number of hours}
\end{htmlonly}
\begin{code}

   public String format()\begin{hide} {
      return format (getSeconds());
   }\end{hide}
\end{code}
  \begin{tabb}  Converts the CPU time used by the program since its last
   call to \method{init}{} for this \texttt{Abstract\-Chrono} to a
  \class{String} in  the \texttt{HH:MM:SS.xx} format.
  \end{tabb}
\begin{htmlonly}
   \return{the string representation of the CPU time}
\end{htmlonly}
\begin{code}

   public static String format (double time)\begin{hide} {
      int second, hour, min, centieme;
      hour = (int)(time/3600.0);
      if (hour > 0) time -= ((double)hour*3600.0);
      min = (int)(time/60.0);
      if (min > 0) time -= ((double)min*60.0);
      second = (int)time;
      centieme = (int)(100.0*(time - (double)second) + 0.5);
      return String.valueOf (hour) + ":" +
                      min + ":" +
                      second + "." +
                      centieme;
   }\end{hide}
\end{code}
  \begin{tabb}  Converts the time \texttt{time}, given in seconds, to a
  \class{String} in the \texttt{HH:MM:SS.xx} format.
  \end{tabb}
\begin{htmlonly}
   \return{the string representation of the time \texttt{time}}
\end{htmlonly}
\begin{code}\begin{hide}
}\end{hide}
\end{code}
